+Mon Aug 16 6:60:53 1999 Owen Taylor <otaylor@redhat.com>
+
+ * gdk/tmpl/properties.sgml
+ gdk/tmpl/selections.sgml
+ gdk/tmpl/input_devices.sgml: Documented
+
+ * gdk/gdk-sections.txt: Moved around types for
+ input devices properties and selections, marked
+ a few functions as private.
<FILE>selections</FILE>
GdkSelection
GdkSelectionType
+GdkTarget
gdk_selection_owner_set
gdk_selection_owner_get
gdk_selection_convert
<TITLE>Properties and Atoms</TITLE>
<FILE>properties</FILE>
GdkAtom
-GdkPropertyState
-GdkPropMode
-GdkTarget
gdk_text_property_to_text_list
gdk_free_text_list
gdk_string_to_compound_text
gdk_atom_name
gdk_property_get
gdk_property_change
+GdkPropMode
gdk_property_delete
</SECTION>
<TITLE>Input Devices</TITLE>
<FILE>input_devices</FILE>
GDK_CORE_POINTER
-GdkExtensionMode
-GdkDeviceKey
-GdkDeviceInfo
-gdk_input_init
-gdk_input_exit
gdk_input_list_devices
+GdkDeviceInfo
+GdkDeviceKey
gdk_input_set_extension_events
+GdkExtensionMode
gdk_input_set_source
GdkInputSource
gdk_input_set_mode
gdk_input_window_get_pointer
gdk_input_motion_events
GdkTimeCoord
+
+<SUBSECTION Private>
+gdk_input_init
+gdk_input_exit
</SECTION>
<SECTION>
GdkEventFocus
GdkEventConfigure
GdkEventProperty
+GdkPropertyState
GdkEventSelection
GdkEventProximity
GdkEventClient
@time:
@state:
+<!-- ##### ENUM GdkPropertyState ##### -->
+<para>
+
+</para>
+
+@GDK_PROPERTY_NEW_VALUE:
+@GDK_PROPERTY_DELETE:
+
<!-- ##### STRUCT GdkEventSelection ##### -->
<para>
Input Devices
<!-- ##### SECTION Short_Description ##### -->
-
+Functions for handling extended input devices.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+In addition to the normal keyboard and mouse input devices, GTK+ also
+contains support for <firstterm>extended input devices</firstterm>. In
+particular, this support is targeted at graphics tablets. Graphics
+tablets typically return sub-pixel positioning information and possibly
+information about the pressure and tilt of the stylus. Under
+X, the support for extended devices is done through the
+<firstterm>XInput</firstterm> extension.
+</para>
+<para>
+Because handling extended input devices may involve considerable
+overhead, they need to be turned on for each #GdkWindow
+individually using gdk_input_set_extension_events().
+(Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()).
+As an additional complication, depending on the support from
+the windowing system, its possible that a normal mouse
+cursor will not be displayed for a particular extension
+device. If an application does not want to deal with displaying
+a cursor itself, it can ask only to get extension events
+from devices that will display a cursor, by passing the
+%GDK_EXTENSION_EVENTS_CURSOR value to
+gdk_input_set_extension_events(). Otherwise, the application
+must retrieve the device information using gdk_input_list_devices(),
+check the <structfield>has_cursor</structfield> field, and,
+if it is %FALSE, draw a cursor itself when it receives
+motion events.
+</para>
+<para>
+Each pointing device is assigned a unique integer ID; events from a
+particular device can be identified by the
+<structfield>deviceid</structfield> field in the event structure. The
+events generated by pointer devices have also been extended to contain
+<structfield>pressure</structfield>, <structfield>xtilt</structfield>
+and <structfield>ytilt</structfield> fields which contain the extended
+information reported as additional <firstterm>valuators</firstterm>
+from the device. The <structfield>pressure</structfield> field is a
+a double value ranging from 0.0 to 1.0, while the tilt fields are
+double values ranging from -1.0 to 1.0. (With -1.0 representing the
+maximum title to the left or up, and 1.0 representing the maximum
+tilt to the right or down.)
+</para>
+<para>
+One additional field in each event is the
+<structfield>source</structfield> field, which contains an
+enumeration value describing the type of device; this currently
+can be one of
+%GDK_SOURCE_MOUSE,
+ %GDK_SOURCE_PEN,
+%GDK_SOURCE_ERASER,
+or %GDK_SOURCE_CURSOR. This field is present to allow simple
+applications to (for instance) delete when they detect eraser
+devices without having to keep track of complicated per-device
+settings.
+</para>
+<para>
+Various aspects of each device may be configured. The easiest way of
+creating a GUI to allow the user to conifigure such a device
+is to use to use the #GtkInputDialog widget in GTK+.
+However, even when using this widget, application writers
+will need to directly query and set the configuration parameters
+in order to save the state between invocations of the application.
+The configuration of devices is queried using gdk_input_list_devices.
+Each device must is activated using gdk_input_set_mode(), which
+also controls whether the device's range is mapped to the
+entire screen or to a single window. The mapping of the valuators of
+the device onto the predefined valuator types is set using
+gdk_input_set_axes. And the source type for each device
+can be set with gdk_input_set_source().
+</para>
+<para>
+Devices may also have associated <firstterm>keys</firstterm>
+or macro buttons. Such keys can be globally set to map
+into normal X keyboard events. The mapping is set using
+gdk_input_set_key().
+</para>
+<para>
+The interfaces in this section will most likely be considerably
+modified in the future to accomodate devices that may have different
+sets of additional valuators than the pressure xtilt and ytilt.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO GDK_CORE_POINTER ##### -->
<para>
-
+This macro contains an integer value representing
+the device ID for the core pointer device.
</para>
-<!-- ##### ENUM GdkExtensionMode ##### -->
+<!-- ##### FUNCTION gdk_input_list_devices ##### -->
<para>
-
+Lists all available input devices, along with their
+configuration information.
</para>
-@GDK_EXTENSION_EVENTS_NONE:
-@GDK_EXTENSION_EVENTS_ALL:
-@GDK_EXTENSION_EVENTS_CURSOR:
-
-<!-- ##### STRUCT GdkDeviceKey ##### -->
-<para>
-
-</para>
+@Returns: A #GList of #GdkDeviceInfo structures. This list
+ is internal data of GTK+ and should not be modified
+ or freed.
-@keyval:
-@modifiers:
<!-- ##### STRUCT GdkDeviceInfo ##### -->
<para>
-
-</para>
-
-@deviceid:
-@name:
-@source:
-@mode:
-@has_cursor:
-@num_axes:
-@axes:
-@num_keys:
-@keys:
-
-<!-- ##### FUNCTION gdk_input_init ##### -->
-<para>
-
+The #GdkDeviceInfo structure contains information about a
+device. It has the following fields:
</para>
+@deviceid: a unique integer ID for this device.
+@name: the human-readable name for the device.
+@source: the type of device.
+@mode: a value indicating whether the device is enabled and
+ how the device coordinates map to the screen.
+@has_cursor: if %TRUE, a cursor will be displayed indicating
+ the current on-screen location to the user. Otherwise,
+ the application is responsible for drawing a cursor
+ itself.
+@num_axes: the number of axes for this device.
+@axes: a pointer to an array of GdkAxisUse values which
+ give the mapping of axes onto the possible valuators
+ for a GDK device.
+@num_keys: the number of macro buttons.
+@keys: a pointer to an array of #GdkDeviceKey structures
+ which describe what key press events are generated
+ for each macro button.
-
-<!-- ##### FUNCTION gdk_input_exit ##### -->
+<!-- ##### STRUCT GdkDeviceKey ##### -->
<para>
-
+The #GdkDeviceKey structure contains information
+about the mapping of one device macro button onto
+a normal X key event. It has the following fields:
</para>
+@keyval: the keyval to generate when the macro button is pressed.
+ If this is 0, no keypress will be generated.
+@modifiers: the modifiers set for the generated key event.
-
-<!-- ##### FUNCTION gdk_input_list_devices ##### -->
+<!-- ##### FUNCTION gdk_input_set_extension_events ##### -->
<para>
-
+Turns extension events on or off for a particular window,
+and specifies the event mask for extension events.
</para>
-@Returns:
+@window: a #GdkWindow.
+@mask: the event mask
+@mode: the type of extension events that are desired.
-<!-- ##### FUNCTION gdk_input_set_extension_events ##### -->
+<!-- ##### ENUM GdkExtensionMode ##### -->
<para>
-
+An enumeration used to specify which extension events
+are desired for a particular widget.
</para>
-@window:
-@mask:
-@mode:
-
+@GDK_EXTENSION_EVENTS_NONE: no extension events are desired.
+@GDK_EXTENSION_EVENTS_ALL: all extension events are desired.
+@GDK_EXTENSION_EVENTS_CURSOR: extension events are desired only if a cursor
+ will be displayed for the device.
<!-- ##### FUNCTION gdk_input_set_source ##### -->
<para>
-
+Sets the source type for a device.
</para>
-@deviceid:
-@source:
+@deviceid: the device to configure
+@source: the new source type.
<!-- ##### ENUM GdkInputSource ##### -->
<para>
-
+An enumeration describing the type of an input device
+in general terms.
</para>
-@GDK_SOURCE_MOUSE:
-@GDK_SOURCE_PEN:
-@GDK_SOURCE_ERASER:
-@GDK_SOURCE_CURSOR:
+@GDK_SOURCE_MOUSE: the device is a mouse. (This will be reported for the core
+ pointer, even if it is something else, such as a trackball.)
+@GDK_SOURCE_PEN: the device is a stylus of a graphics tablet or similar device.
+@GDK_SOURCE_ERASER: the device is an eraser. Typically, this would be the other end
+ of a stylus on a graphics tablet.
+@GDK_SOURCE_CURSOR: the device is a graphics tablet "puck" or similar device.
<!-- ##### FUNCTION gdk_input_set_mode ##### -->
<para>
-
+Enables or disables a device, and determines how the
+device maps onto the screen.
</para>
-@deviceid:
-@mode:
-@Returns:
+@deviceid: the device to configure.
+@mode: the new mode.
+@Returns: %TRUE if the device supports the given mode, otherwise
+ %FALSE and the device's mode is unchanged.
<!-- ##### ENUM GdkInputMode ##### -->
<para>
-
+An enumeration that describes the mode of an input device.
</para>
-@GDK_MODE_DISABLED:
-@GDK_MODE_SCREEN:
-@GDK_MODE_WINDOW:
+@GDK_MODE_DISABLED: the device is disabled and will not report any events.
+@GDK_MODE_SCREEN: the device is enabled. The device's coordinate space
+ maps to the entire screen.
+@GDK_MODE_WINDOW: the device is enabled. The device's coordinate space
+ is mapped to a single window. The manner in which this window
+ is chosen is undefined, but it will typically be the same
+ way in which the focus window for key events is determined.
<!-- ##### FUNCTION gdk_input_set_axes ##### -->
<para>
-
+Sets the mapping of the axes (valuators) of a device
+onto the predefined valuator types that GTK+ understands.
</para>
-@deviceid:
-@axes:
+@deviceid: the device to configure.
+@axes: an array of GdkAxisUse. This length of this array
+ must match the number of axes for the device.
<!-- ##### ENUM GdkAxisUse ##### -->
<para>
-
+An enumeration describing the way in which a device
+axis (valuator) maps onto the predefined valuator
+types that GTK+ understands.
</para>
-@GDK_AXIS_IGNORE:
-@GDK_AXIS_X:
-@GDK_AXIS_Y:
-@GDK_AXIS_PRESSURE:
-@GDK_AXIS_XTILT:
-@GDK_AXIS_YTILT:
-@GDK_AXIS_LAST:
+@GDK_AXIS_IGNORE: the axis is ignored.
+@GDK_AXIS_X: the axis is used as the x axis.
+@GDK_AXIS_Y: the axis is used as the y axis.
+@GDK_AXIS_PRESSURE: the axis is used for pressure information.
+@GDK_AXIS_XTILT: the axis is used for x tilt information.
+@GDK_AXIS_YTILT: the axis is used for x tilt information.
+@GDK_AXIS_LAST: a constant equal to the numerically highest axis value.
<!-- ##### FUNCTION gdk_input_set_key ##### -->
<para>
-
+Sets the key event generated when a macro button is pressed.
</para>
-@deviceid:
-@index:
-@keyval:
-@modifiers:
+@deviceid: the device to configure.
+@index: the index of the macro button.
+@keyval: the key value for the #GdkKeypressEvent to generate.
+ (a value of 0 means no event will be generated.)
+@modifiers: the modifier field for the generated
+ #GdkKeyPressEvent.
<!-- ##### FUNCTION gdk_input_window_get_pointer ##### -->
<para>
-
+Returns information about the current position of the pointer
+within a window, including extended device information.
+Any of the return parameters may be %NULL, in which case,
+they will be ignored.
</para>
-@window:
-@deviceid:
-@x:
-@y:
-@pressure:
-@xtilt:
-@ytilt:
-@mask:
+@window: a #GdkWindow.
+@deviceid: a device ID.
+@x: location to store current x postion.
+@y: location to store current y postion.
+@pressure: location to store current pressure.
+@xtilt: location to store current tilt in the x direction.
+@ytilt: location to store current tilt in the y direction.
+@mask: location to store the current modifier state.
<!-- ##### FUNCTION gdk_input_motion_events ##### -->
<para>
-
+Retrieves the motion history for a given device/window pair.
</para>
-@window:
-@deviceid:
-@start:
-@stop:
-@nevents_return:
-@Returns:
+@window: a #GdkWindow.
+@deviceid: the device for which to retrieve motion history.
+@start: the start time.
+@stop: the stop time.
+@nevents_return: location to store the number of events returned.
+@Returns: a newly allocated array containing all the events
+ from @start to @stop. This array should be freed
+ with g_free() when you are finished using it.
<!-- ##### STRUCT GdkTimeCoord ##### -->
<para>
-
+The #GdkTimeCoord structure stores a single event in a
+motion history. It contains the following fields:
</para>
-@time:
-@x:
-@y:
-@pressure:
-@xtilt:
-@ytilt:
+@time: The timestamp for this event.
+@x: the x position.
+@y: the y position.
+@pressure: the pressure.
+@xtilt: the tilt in the x direction.
+@ytilt: the tilt in the y direction.
Properties and Atoms
<!-- ##### SECTION Short_Description ##### -->
-
+functions to manipulate properties on windows.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+Each window under X can have any number of associated
+<firstterm>properties</firstterm> attached to it.
+Properties are arbitrary chunks of data identified by
+<firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
+is a numeric index into a string table on the X server. They are used
+to transfer strings efficiently between clients without
+having to transfer the entire string.) A property
+has an associated type, which is also identified
+using an atom.
</para>
-
-<!-- ##### SECTION See_Also ##### -->
<para>
-
+A property has an associated <firstterm>format</firstterm>,
+an integer describing how many bits are in each unit
+of data inside the property. It must be 8, 16, or 32.
+When data is transfered between the server and client,
+if they are of different endianesses it will be byteswapped
+as necessary according to the format of the property.
+Note that on the client side, properties of format 32
+will be stored with one unit per <emphasis>long</emphasis>,
+even if a long integer has more than 32 bits on the platform.
+(This decision was apparently made for Xlib to maintain
+compatibility with programs that assumed longs were 32
+bits, at the expense of programs that knew better.)
</para>
-
-<!-- ##### TYPEDEF GdkAtom ##### -->
<para>
-
+The functions in this section are used to add, remove
+and change properties on windows, to convert atoms
+to and from strings and to manipulate some types of
+data commonly stored in X window properties.
</para>
-
-<!-- ##### ENUM GdkPropertyState ##### -->
-<para>
-
-</para>
-
-@GDK_PROPERTY_NEW_VALUE:
-@GDK_PROPERTY_DELETE:
-
-<!-- ##### ENUM GdkPropMode ##### -->
+<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-@GDK_PROP_MODE_REPLACE:
-@GDK_PROP_MODE_PREPEND:
-@GDK_PROP_MODE_APPEND:
-
-<!-- ##### ENUM GdkTarget ##### -->
+<!-- ##### TYPEDEF GdkAtom ##### -->
<para>
-
+A numeric type representing a string as an index into a table
+of strings on the X server.
</para>
-@GDK_TARGET_BITMAP:
-@GDK_TARGET_COLORMAP:
-@GDK_TARGET_DRAWABLE:
-@GDK_TARGET_PIXMAP:
-@GDK_TARGET_STRING:
<!-- ##### FUNCTION gdk_text_property_to_text_list ##### -->
<para>
-
+Convert a text string from the encoding as it is stored in
+a property into an array of strings in the encoding of
+the current local. (The elements of the array represent
+the null-separated elements of the original text string.)
</para>
-@encoding:
-@format:
-@text:
-@length:
-@list:
-@Returns:
+@encoding: an atom representing the encoding. The most common
+ values for this are <literal>STRING</literal>,
+ or <literal>COMPOUND_TEXT</literal>. This is
+ value used as the type for the property.
+@format: the format of the property.
+@text: the text data.
+@length: the length of the property, in item.s
+@list: location to store a terminated array of strings
+ in the encoding of the current locale. This
+ array should be freed using gdk_free_text_list().
+@Returns: the number of strings stored in @list, or 0,
+ if the conversion failed.
<!-- ##### FUNCTION gdk_free_text_list ##### -->
<para>
-
+Free the array of strings created by
+gdk_text_property_to_text_list().
</para>
-@list:
+@list: the value stored in the @list parameter by
+ a call to gdk_text_property_to_text_list().
<!-- ##### FUNCTION gdk_string_to_compound_text ##### -->
<para>
-
+Convert a string from the encoding of the current locale
+into a form suitable for storing in a window property.
</para>
-@str:
-@encoding:
-@format:
-@ctext:
-@length:
-@Returns:
+@str: a null-terminated string.
+@encoding: location to store the encoding atom (to be used as the type for the property).
+@format: location to store the format for the property.
+@ctext: location to store newly allocated data for the property.
+@length: location to store the length of @ctext in items.
+@Returns: 0 upon sucess, non-zero upon failure.
<!-- ##### FUNCTION gdk_free_compound_text ##### -->
<para>
-
+Free the data returned from gdk_string_to_compound_text().
</para>
-@ctext:
+@ctext: The pointer stored in @ctext from a call to gdk_string_to_compound_text().
<!-- ##### FUNCTION gdk_atom_intern ##### -->
<para>
-
+Find or create an atom corresponding to a given string.
</para>
-@atom_name:
-@only_if_exists:
-@Returns:
+@atom_name: a string.
+@only_if_exists: if %TRUE, do not create a new atom, but
+ just return the atom if it already exists.
+@Returns: the atom corresponding to @atom_name, or, if
+ @only_if_exists is false, and an atom does not
+ already exists for the string, %GDK_NONE.
<!-- ##### FUNCTION gdk_atom_name ##### -->
<para>
-
+Determine the string corresponding to an atom.
</para>
-@atom:
-@Returns:
+@atom: a #GdkAtom.
+@Returns: a newly allocated string containing the string
+ corresponding to @atom. When you are done
+ with the return value, you should free it
+ using g_free().
<!-- ##### FUNCTION gdk_property_get ##### -->
<para>
-
+Retrieves a portion of the contents of a property. If the
+property does not exist, then the function returns FALSE,
+and %GDK_NONE will be stored in @actual_property_type.
+
+Note: the <function>XGetWindowProperty()</function>
+function that gdk_property_get()
+uses has a very confusing and complicated set of semantics.
+Unfortunately, gdk_property_get() makes the situation
+worse instead of better (the semantics should be considered
+undefined), and also prints warnings to stderr in cases where it
+should return a useful error to the program. You are advised to use
+<function>XGetWindowProperty()</function>
+directly until a replacement function for gdk_property_get()
+is provided.
</para>
-@window:
-@property:
-@type:
-@offset:
-@length:
-@pdelete:
-@actual_property_type:
-@actual_format:
-@actual_length:
-@data:
-@Returns:
+@window: a #GdkWindow.
+@property: the property to retrieve.
+@type: the desired property type, or 0, if any type of data
+ is acceptable. If this does not match the actual
+ type, then @actual_format and @actual_length will
+ be filled in, a warning will be printed to stderr
+ and no data will be returned.
+@offset: the offset into the property at which to begin
+ retrieving data. (in 4 byte units!)
+@length: the length of the data to delete. (in bytes, but
+ the actual retrieved length will be the next
+ integer multiple multiple of four greater than
+ this!)
+@pdelete: if %TRUE, delete the property after retrieving the
+ data.
+@actual_property_type: location to store the actual type of
+ the property.
+@actual_format: location to store the actual format of the data.
+@actual_length: location to store the length of the retrieved
+ data, in bytes.
+@data: location to store a pointer to the data. The retrieved
+ data should be freed with g_free() when you are finished
+ using it.
+@Returns: %TRUE if data was sucessfully received and stored
+ in @data, otherwise %FALSE.
<!-- ##### FUNCTION gdk_property_change ##### -->
<para>
-
+Change the contents of a property on a window.
</para>
-@window:
-@property:
-@type:
-@format:
-@mode:
-@data:
-@nelements:
+@window: a #GdkWindow.
+@property: the property to change.
+@type: the new type for the property. If @mode is
+ %GDK_PROP_MODE_REPLACE or %GDK_PROP_MODE_APPEND, then this
+ must match the existing type or an error will occur.
+@format: the new format for the property. If @mode is
+ %GDK_PROP_MODE_REPLACE or %GDK_PROP_MODE_APPEND, then this
+ must match the existing format or an error will occur.
+@mode: a value describing how the new data is to be combined
+ with the current data.
+@data: the data
+ (a <literal>guchar *</literal>
+ <literal>gushort *</literal>, or
+ <literal>gulong *</literal>, depending on @format), cast to a
+ <literal>guchar *</literal>.
+@nelements: the number of elements of size determined by the format,
+ contained in @data.
-<!-- ##### FUNCTION gdk_property_delete ##### -->
+<!-- ##### ENUM GdkPropMode ##### -->
<para>
+Describes how existing data is combined with new data when
+using gdk_property_change().
+</para>
+
+@GDK_PROP_MODE_REPLACE: the new data replaces the existing data.
+@GDK_PROP_MODE_PREPEND: the new data is prepended to the existing data.
+@GDK_PROP_MODE_APPEND: the new data is appended to the existing data.
+<!-- ##### FUNCTION gdk_property_delete ##### -->
+<para>
+Delete a property from a window.
</para>
-@window:
-@property:
+@window: a #GdkWindow.
+@property: the property to delete.
Selections
<!-- ##### SECTION Short_Description ##### -->
-
+functions for transfering data via the X selection mechanism.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The X selection mechanism provides a way to transfer
+arbitrary chunks of data between programs.
+A <firstterm>selection</firstterm> is a essentially
+a named clipboard, identified by a string interned
+as a #GdkAtom. By claiming ownership of a selection,
+an application indicates that it will be responsible
+for supplying its contents. The most common
+selections are <literal>PRIMARY</literal> and
+<literal>CLIPBOARD</literal>.
+</para>
+<para>
+The contents of a selection can be represented in
+a number of formats, called <firstterm>targets</firstterm>.
+Each target is identified by an atom. A list of
+all possible targets supported by the selection owner
+can be retrieved by requesting the special target
+<literal>TARGETS</literal>. When a selection is
+retrieved, the data is accompanied by a type
+(an atom), and a format (an integer, representing
+the number of bits per item). See <xref
+linkend="gdk-Properties-and-Atoms"> for more information.
+</para>
+<para>
+The functions in this section only contain the lowlevel
+parts of the selection protocol. A considerably more
+complicated implementation is needed on top of this.
+GTK+ contains such an implementation in the functions
+in <literal>gtkselection.h</literal> and programmers
+should use those functions instead of the ones presented
+here. If you plan to implement selection handling
+directly on top of the functions here, you should refer
+to the X Inter-client Communication Conventions Manual
+(ICCCM).
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### ENUM GdkSelection ##### -->
<para>
-
+The #GdkSelection enumeration contains predefined
+atom values for several common selections.
</para>
-@GDK_SELECTION_PRIMARY:
-@GDK_SELECTION_SECONDARY:
+@GDK_SELECTION_PRIMARY: The primary X selection. Programs
+typically claim this selection when the user
+selects text and paste its contents in response
+to a middle button press.
+@GDK_SELECTION_SECONDARY: An additional X selection.
<!-- ##### ENUM GdkSelectionType ##### -->
<para>
+The #GdkSelectionType enumeration contains predefined
+atom values used to represent the types of data transferred
+in response to a request for a target. See the
+ICCCM for details about what data should be transferred
+for each of these types. Other atoms can be used,
+and the recommended practice for GTK+ is to to use mime
+types for this purpose. However, supporting these types
+may be useful for compatibility with older programs.
+</para>
+@GDK_SELECTION_TYPE_ATOM: An atom. (format 32)
+@GDK_SELECTION_TYPE_BITMAP: A bitmap ID. (format 32)
+@GDK_SELECTION_TYPE_COLORMAP: A colormap ID. (format 32)
+@GDK_SELECTION_TYPE_DRAWABLE: A drawable ID. (format 32)
+@GDK_SELECTION_TYPE_INTEGER: An integer. (format 32)
+@GDK_SELECTION_TYPE_PIXMAP: A pixmap ID. (format 32)
+@GDK_SELECTION_TYPE_WINDOW: A window ID. (format 32)
+@GDK_SELECTION_TYPE_STRING: A string encoded
+ in ISO Latin-1. (With the additional of <symbol>TAB</symbol>
+ and <symbol>NEWLINE</symbol>.) (format 8)
+
+<!-- ##### ENUM GdkTarget ##### -->
+<para>
+The #GdkTarget enumeration contains predefined atom values which are
+used to describe possible targets for a selection. Other atoms can be
+used, and the recommended practice for GTK+ is to to use mime types
+for this purpose. However, supporting these types may be useful for
+compatibility with older programs.
</para>
-@GDK_SELECTION_TYPE_ATOM:
-@GDK_SELECTION_TYPE_BITMAP:
-@GDK_SELECTION_TYPE_COLORMAP:
-@GDK_SELECTION_TYPE_DRAWABLE:
-@GDK_SELECTION_TYPE_INTEGER:
-@GDK_SELECTION_TYPE_PIXMAP:
-@GDK_SELECTION_TYPE_WINDOW:
-@GDK_SELECTION_TYPE_STRING:
+@GDK_TARGET_BITMAP: A bitmap ID.
+@GDK_TARGET_COLORMAP: A colormap ID.
+@GDK_TARGET_DRAWABLE: A drawable ID.
+@GDK_TARGET_PIXMAP: A pixmap ID.
+@GDK_TARGET_STRING: A string encoded in ISO Latin-1.
+ (With the additional of <symbol>TAB</symbol>
+ and <symbol>NEWLINE</symbol>.)
<!-- ##### FUNCTION gdk_selection_owner_set ##### -->
<para>
-
+Set the owner of the given selection.
</para>
-@owner:
-@selection:
-@time:
-@send_event:
-@Returns:
+@owner: a #GdkWindow or NULL to indicate that the
+ the owner for the given should be unset.
+@selection: an atom identifying a selection.
+@time: timestamp to use when setting the selection.
+ If this is older than the timestamp given last
+ time the owner was set for the given selection, the
+ request will be ignored.
+@send_event: if %TRUE, and the new owner is different
+ from the current owner, the current owner
+ will be sent a SelectionClear event.
+@Returns: %TRUE if the selection owner was succesfully
+ changed to @owner, otherwise %FALSE.
<!-- ##### FUNCTION gdk_selection_owner_get ##### -->
<para>
-
+Determine the owner of the given selection.
</para>
-@selection:
-@Returns:
+@selection: an atom indentifying a selection.
+@Returns: if there is a selection owner for this window,
+ and it is a window known to the current process,
+ the #GdkWindow that owns the selection, otherwise
+ NULL. Note that the return value may be owned
+ by a different process if a foreign window
+ was previously created for that window, but
+ a new foreign window will never be created by
+ this call.
<!-- ##### FUNCTION gdk_selection_convert ##### -->
<para>
-
+Retrieve the contents of a selection in a given
+form.
</para>
-@requestor:
-@selection:
-@target:
-@time:
-
+@requestor: a #GdkWindow.
+@selection: an atom identifying the selection to get the
+ contents of.
+@target: the form in which to retrieve the selection.
+@time: the timestamp to use when retrieving the
+ selection. The selection owner may refuse the
+ request if it did not own the selection at
+ the time indicated by the timestamp.
<!-- ##### FUNCTION gdk_selection_property_get ##### -->
<para>
-
+Retrieve selection data that was stored by the selection
+data in response to a call to gdk_selection_convert()
</para>
-@requestor:
-@data:
-@prop_type:
-@prop_format:
-@Returns:
+@requestor: the window on which the data is stored
+@data: location to store a pointer to the retrieved data.
+ If the retrieval failed, NULL we be stored here, otherwise, it
+ will be non-NULL and the returned data should be freed with g_free()
+ when you are finished using it. The length of the
+ allocated memory is one more than the the length
+ of the returned data, and the final byte will always
+ be zero, to ensure null-termination of strings.
+@prop_type: location to store the type of the property.
+@prop_format: location to store the format of the property.
+@Returns: the length of the retrieved data.
<!-- ##### FUNCTION gdk_selection_send_notify ##### -->
<para>
-
+Send a response to SelectionRequest event.
</para>
-@requestor:
-@selection:
-@target:
-@property:
-@time:
+@requestor: window to which to deliver response.
+@selection: selection that was requested.
+@target: target that was selected.
+@property: property in which the selection owner stored the
+ data, or %GDK_NONE to indicate that the request
+ was rejected.
+@time: timestamp.
projects / gtk4.git / commitdiff